@ipld/dag-ucan

@ipld/dag-ucan

An implementation of UCANs in IPLD via Advanced Data Layout (ADL), designed for use with multiformats.

Overview

This library implements ADL for representing UCANs natively in IPLD. It uses DAG-CBOR as a primary encoding, which is hash consistent and more compact than a secondary RAW JWT encoding. Every UCAN in either encoding can be formatted into a valid JWT string and consumed by other spec compliant UCAN implementations. However UCANs issued by other libraries may end up in represented in secondory RAW JWT encoding, that is because whitespaces and key order in JWT affects signatures and there for can't be represented accurately in CBOR. When parsing UCANs library will use CBOR representation and fallback to RAW JWT, which allows interop with all existing tokens in the wild.

Primary Representation

UCANs in primary representation are encoded in DAG-CBOR and have following IPLD schema:

type UCAN struct {
  v String
  s Signature

  -- Issuer DID (sender)
  iss SigningKey
  -- Audience DID (receiver)
  aud SigningKey
  -- Not Before UTC Unix Timestamp (valid from)
  nbf optional Int
  -- Expiration UTC Unix Timestamp (valid until)
  exp nullable Int
  -- Nonce
  nnc optional String
  -- Facts (asserted, signed data)
  fct [Fact]
  -- Attenuations
  att [Capability]
  -- Proof of delegation (hash-linked UCANs)
  prf [&UCAN]
} representation map {
  field fct default []
  field prf default []
}

exp

type Capability struct {
  with Resource
  can Ability
  nb Any
}

type Fact { String: Any }


-- The resource pointer in URI format
type Resource = String

-- Must be all lower-case `/` delimeted with at least one path segment
type Ability = String

-- Signature is computed by seralizing header & body
-- into corresponding JSON with DAG-JSON (to achieve
-- for hash consitency) then encoded into base64 and
-- then signed by issuers private key
type Signature = Bytes

-- multicodec tagged public key
-- 0xed       Ed25519
-- 0x1205     RSA
type SigningKey = Bytes

API

import * as UCAN from "@ipld/dag-ucan"

UCAN.parse(jwt: string): UCAN.View

Parses UCAN formatted as JWT string into a representatino that can be encoded, formatted and queried.

const ucan = UCAN.parse(jwt)
ucan.issuer.did() // did:key:z6Mkk89bC3JrVqKie71YEcc5M1SMVxuCgNx6zLZ8SYJsxALi

UCAN.format(ucan: UCAN.UCAN): string

Formats UCAN into a JWT string.

UCAN.format(UCAN.parse(jwt)) === jwt // true

UCAN.encode(ucan: UCAN.UCAN): Uint8Array

Encodes UCAN into a binary representation.

UCAN.encode(UCAN.parse(jwt)) // Uint8Array(679)

UCAN.decode(bytes: Uint8Array): UCAN.UCAN

Decodes UCAN from binary representation into object representation.

UCAN.decode(UCAN.encode(ucan))

UCAN.issue(options: UCAN.UCANOptions): Promise<UCAN.UCAN>

Issues a signed UCAN.

Please note that no capability or time bound validation takes place.

const ucan = await UCAN.issue({
  issuer: alice,
  audience: bob,
  capabilities: [
    {
      can: "fs/read",
      with: `storage://${alice.did()}/public/photos/`,
    },
    {
      can: "pin/add",
      with: alice.did(),
    },
  ],
})

Embedding Proofs

While not recommended, it is possible to inline proofs inside a single UCAN using CIDs with identity multihash:

import { identity } from "multiformats/hashes/identity"
const proof = await UCAN.issue({
  issuer: alice,
  audience: bob,
  capabilities: [{ can: "store/add", with: alice.did() }],
})

const delegation = await UCAN.issue({
  issuer: bob,
  audience: mallory,
  capabilities: proof.capabilities,
  proofs: [await UCAN.link(proof, { hasher: identity })],
})

Changelog

4.0.0-beta (2022-09-26)

⚠ BREAKING CHANGES

• 0.9 spec (#57)

Features

• 0.9 spec (#57) (873845a)